-
-
Notifications
You must be signed in to change notification settings - Fork 1.9k
Documentation conversion into Mkdocs #7609
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
…ocs-conversion
- Import Jekyll material from graphic-library-docs repository. - Remove (most) mentions of languages other than Python and JavaScript. - Add Makefile to re-run commands.
… into mkdocs-conversion
…nto mkdocs-conversion
…the html snippets for each file under 'docs/tmp/'
…om the 'mkdocs.yml' file.
- Add `./Makefile` with commands to rebuild documentation using the
commands shown below. (We'll tidy this up in the final step.)
- `make examples`
- `make reference`
- `make build`
- Move scripts from `./docs/bin` to `./bin` and adjust paths in
scripts as needed to pick up the right files and to build into
`./tmp`.
- Modify `./mkdocs.yml` to build from `./tmp`.
- Modify `./.gitignore` to ignore `./tmp`.
Note that this is only a step toward the final cleaned-up version: the
next step is to move `./docs/_posts` into the root directory, then
remove `./docs` entirely and build the site into `./docs` rather than
into `./doc`.
refactor: move documentation generation into the root directory
- and remove last vestiges of Jekyll
…into mkdocs-conversion
| # Manage plotly.js documentation. | ||
|
|
||
| RUN = uv run | ||
| SCHEMA_SRC = test/plot-schema.json | ||
| HANDWRITTEN = content | ||
| TMP = tmp | ||
|
|
||
| EXAMPLES_DIR = ${HANDWRITTEN}/plotly_js | ||
| EXAMPLES_IN := $(shell find "${EXAMPLES_DIR}" -name '*.html') | ||
| EXAMPLES_TMP = ${TMP}/javascript | ||
| EXAMPLES_OUT = ${EXAMPLES_TMP}/axes/index.html # could be any of the generated files | ||
|
|
||
| REFERENCE_DIR = ${HANDWRITTEN}/reference_pages/javascript/ | ||
| REFERENCE_IN := $(wildcard ${REFERENCE_DIR}/*.html) | ||
| REFERENCE_TMP = ${TMP}/reference | ||
| REFERENCE_OUT = ${REFERENCE_TMP}/bar/index.html # could be any of the generated files | ||
|
|
||
| DOCS_DIR=docs | ||
| DOCS_OUT=${DOCS_DIR}/sitemap.xml | ||
|
|
||
| ## commands: show available commands | ||
| commands: | ||
| @grep -h -E '^##' ${MAKEFILE_LIST} | sed -e 's/## //g' | column -t -s ':' | ||
|
|
||
| ## docs: rebuild full documentation in `./docs` | ||
| .PHONY: docs | ||
| docs: ${DOCS_OUT} | ||
|
|
||
| ${DOCS_OUT}: ${EXAMPLES_OUT} ${REFERENCE_OUT} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Could we add to the docs contributing guide on how to build the docs, and maybe a GitHub action that runs the required steps to test generating the output.
|
General comment on file organization: I'd like to minimize the number of files added at the top level of this repo. Ideally anything related to the docs should be contained inside a |
Co-authored-by: Cameron DeCoster <cameron.decoster@gmail.com>
Co-authored-by: Cameron DeCoster <cameron.decoster@gmail.com>
…ed old instructions from the old build.
camdecoster
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There are still some bugs to fix, but everything is building for me. Thanks for your diligence on getting this working!
Converted the plotly.js documentation build into Mkdocs
src/traces/image/attributes.jsfor proper Markdown rendering on plotly.py docs' function docstrings.code-highlight.cssapplies syntax highlighting. This is done because the markdown files are HTML snippets.plotly/plotly.js/README.mdand index pages are placed in each individual category of examples underOverview.